Sharing Your Brilliance with the World

Matt Pettis
2019-08-15

… because you are awesome

You see things...

… that others don't see…
… and others need to see…
… let's go to the code.

Your Genius Insights are Eclipsed by Awkward Tooling

Results and comments not together.
Images in another pane (if in RStudio) or saved to separate file.
You have to click around for other pictures.

Your Genius Insights are Eclipsed by Technical Difficulties

Enter R Markdown

… To the code!

Key R Markdown Pieces: Header

Key R Markdown Pieces: Header

Key R Markdown Pieces: Header

Key R Markdown Pieces: Header

Key R Markdown Pieces: Header

Key R Markdown Pieces: Header

Other key features:

Numbering sections
Code folding
Custom CSS

Key R Markdown Pieces: Commentary

Key R Markdown Pieces: Code, Images

Key R Markdown Pieces: Code, Tables

Key R Markdown Use Cases

Automated reports: cron jobs, data integrity checks.
Avoid manual powerpoint presentations.
Taking notes while talking to yourself
Reproducible research

Opinion: How to use Markdown reports

Start report with executive summary and what to expect to see in report, highlights.
As much global setup work done at beginning.
Make analysis sections (see next).
Auto-generate Table of Contents.

Opinion: How to use Markdown reports

Break work into a chunk that answers a question.
Record what you expect to see.
Record what you actually saw.
Output code and artifacts that support the analysis.

Sidebar: RMarkdown vs Notebooks (Jupyter)

… do not use to start fights.
Sequential, linear execution desireable.
Notebooks have source code and output formatting mixed.
- … does not work nicely with git.

Sidebar: RMarkdown vs Notebooks (Jupyter)

… I don't like magic.

Blogdown

You have lots of insights to share, but blast emailing people your insights is found “annoying” to the less enlighted.
Many “easy” website solutions are overkill on one hand, and don't support the tech analysis features nicely on the other hand.

Blogdown: Setup

Install instructions: https://bookdown.org/yihui/blogdown/installation.html
Generate new site: https://bookdown.org/yihui/blogdown/a-quick-example.html

Blogdown: Live Demo

Install blogdown
Create new blogdown site via New Project...
In 'Addins, serve site, and then create new blogpost.
Show in browser.

Blogdown: Netlify deploy

Drag and drop your public/ folder to Netlify.
This example site: https://sad-goldberg-3e7866.netlify.com/
You can also configure to push via github, gitlab, bitbucket, and more.

Blogdown: What is it giving you?

Separate website theming from content production.
Your content is highly leveraged from your RMarkdown skills.
Once configured, you can make a working RMarkdown file, and then just publish it.
Optimized for a static website.
Not locked in to web publishing platform.

Blogdown: What is it giving you?

Bookdown

Bookdown

You have a thematic collection of things to say.
They break naturally into chapters.
Options for distributed editing.
Read online as html, or convert to pdf, ebook, Word Doc for offline reading.

Bookdown: Demo

Summary

RMarkdown for prettier commentary, better documentation.
Blogdown for making sets of posts with very similar machinery to RMarkdown, pushable to website.
Bookdown for a self-contained, well, book, with very similar machinery to RMarkdown.
All of these leverage markdown

Resources: RMarkdown

Definitive books (in bookdown!)
- Markdown: https://bookdown.org/yihui/rmarkdown/
- Blogdown: https://bookdown.org/yihui/blogdown/
- Bookdown: https://bookdown.org/yihui/bookdown/
RMarkdown Cheat sheet: https://www.rstudio.com/resources/cheatsheets/#rmarkdown

Other Links

I don't like notebooks: https://conferences.oreilly.com/jupyter/jup-ny/public/schedule/detail/68282

Thank You

Matt Pettis

Sr. Data Scientist, Trane Inc.

matthew.pettis@gmail.com